home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / lib / mozilla-firefox / idl / nsIExtensionManager.idl < prev    next >
Encoding:
Text File  |  2006-05-08  |  18.9 KB  |  573 lines
  1. /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
  2. /* ***** BEGIN LICENSE BLOCK *****
  3.  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  4.  *
  5.  * The contents of this file are subject to the Mozilla Public License Version
  6.  * 1.1 (the "License"); you may not use this file except in compliance with
  7.  * the License. You may obtain a copy of the License at
  8.  * http://www.mozilla.org/MPL/
  9.  *
  10.  * Software distributed under the License is distributed on an "AS IS" basis,
  11.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12.  * for the specific language governing rights and limitations under the
  13.  * License.
  14.  *
  15.  * The Original Code is the Extension Manager.
  16.  *
  17.  * The Initial Developer of the Original Code is Ben Goodger.
  18.  * Portions created by the Initial Developer are Copyright (C) 2004
  19.  * the Initial Developer. All Rights Reserved.
  20.  *
  21.  * Contributor(s):
  22.  *  Ben Goodger <ben@mozilla.org> (Google Inc.)
  23.  *
  24.  * Alternatively, the contents of this file may be used under the terms of
  25.  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26.  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27.  * in which case the provisions of the GPL or the LGPL are applicable instead
  28.  * of those above. If you wish to allow use of your version of this file only
  29.  * under the terms of either the GPL or the LGPL, and not to allow others to
  30.  * use your version of this file under the terms of the MPL, indicate your
  31.  * decision by deleting the provisions above and replace them with the notice
  32.  * and other provisions required by the GPL or the LGPL. If you do not delete
  33.  * the provisions above, a recipient may use your version of this file under
  34.  * the terms of any one of the MPL, the GPL or the LGPL.
  35.  *
  36.  * ***** END LICENSE BLOCK ***** */
  37.  
  38.  
  39. #include "nsISupports.idl"
  40.  
  41. interface nsIFile;
  42. interface nsIRDFDataSource;
  43. interface nsIUpdateItem;
  44. interface nsIAddonUpdateListener;
  45. interface nsIAddonUpdateCheckListener;
  46. interface nsICommandLine;
  47. interface nsISimpleEnumerator;
  48. interface nsIDirectoryEnumerator;
  49.  
  50. /**
  51.  * Interface representing a location where extensions, themes etc are 
  52.  * installed.
  53.  */
  54. [scriptable, uuid(D3D4DADA-C6EB-11D9-A68F-001124787B2E)]
  55. interface nsIInstallLocation : nsISupports
  56. {
  57.   /**
  58.    * The string identifier of this Install Location
  59.    */
  60.   readonly attribute AString name;
  61.   
  62.   /**
  63.    * An enumeration of nsIFiles for:
  64.    * - locations that contain items
  65.    * - potential dropped-in XPIs
  66.    * Note: This enumeration resolves Text Links to the directories they
  67.    *       refer to.
  68.    */
  69.   readonly attribute nsIDirectoryEnumerator itemLocations;
  70.  
  71.   /**
  72.    * The file system location where items live. Items can be dropped in
  73.    * at this location. Can be null for Install Locations that don't have
  74.    * a file system presence. 
  75.    * Note: This is a clone of the actual location which the caller can 
  76.    *       modify freely.
  77.    */
  78.   readonly attribute nsIFile location;
  79.  
  80.   /**
  81.    * Whether or not this Install Location is on an area of the file system
  82.    * that could be restricted on a restricted-access account, regardless
  83.    * of whether or not the location is restricted with the current user
  84.    * privileges. 
  85.    */
  86.   readonly attribute boolean restricted;
  87.  
  88.   /**
  89.    * Whether or not the user can write to the Install Location with the
  90.    * current access privileges. This is different from restricted because
  91.    * it's not whether or not the location *might* be restricted, it's 
  92.    * whether or not it actually *is* restricted right now.
  93.    */
  94.   readonly attribute boolean canAccess;
  95.  
  96.   /**
  97.    * Constants representing priority of some default Install Locations.
  98.    * XXXben - priority ranking of user-level items vs. global-level items
  99.    *          here is debatable. Should app-system-global trump 
  100.    *          xre-system-user?
  101.    * You should not use the exact values here, you should offset from
  102.    * these values each time you create a new Install Location. Offsetting
  103.    * can be brittle but you should know what Install Locations are being
  104.    * defined for your own application.
  105.    */
  106.   const unsigned long PRIORITY_APP_PROFILE        = 0;
  107.   const unsigned long PRIORITY_APP_SYSTEM_USER    = 10;
  108.   const unsigned long PRIORITY_XRE_SYSTEM_USER    = 100;
  109.   const unsigned long PRIORITY_APP_SYSTEM_GLOBAL  = 1000;
  110.   const unsigned long PRIORITY_XRE_SYSTEM_GLOBAL  = 10000;
  111.     
  112.   /**
  113.    * The priority level of this Install Location in loading. 
  114.    */
  115.   readonly attribute long priority;
  116.   
  117.   /**
  118.    * Gets the directory that contains an item.
  119.    * @param   id
  120.    *          The GUID of the item.
  121.    * @returns The location of the item. 
  122.    */
  123.   nsIFile getItemLocation(in AString id);
  124.  
  125.   /**
  126.    * Retrieves the GUID for an item at the specified location.
  127.    * @param   file
  128.    *          The location where an item might live.
  129.    * @returns The ID for an item that might live at the location specified.
  130.    *
  131.    * N.B. This function makes no promises about whether or not this path is
  132.    *      actually maintained by this Install Location.
  133.    */
  134.   AString getIDForLocation(in nsIFile file);
  135.  
  136.   /**
  137.    * Gets a nsIFile object for a file within an item's directory structure.
  138.    * @param   id
  139.    *          The GUID of the item.
  140.    * @param   path
  141.    *          The path to the file beneath an Extension's directory
  142.    * @returns A file object at the requested location. The file does not
  143.    *          necessarily have to exist.
  144.    */
  145.   nsIFile getItemFile(in AString id, in AString path);
  146.  
  147.   /**
  148.    * Determines whether or not an item's resources are managed by the Extension
  149.    * System or by some other user or process. For example, items linked to by
  150.    * text links are managed by the user, and items linked to from Registry
  151.    * Install Locations are usually managed by other applications or installers.
  152.    *
  153.    * @param   id
  154.    *          The GUID of the item.
  155.    * @returns true if the item's resources are managed independently of the
  156.    *          Extension System, false otherwise.
  157.    */
  158.   boolean itemIsManagedIndependently(in AString id);
  159. };
  160.  
  161. /**
  162.  * Interface representing a system for the installation and management of
  163.  * Extensions, Themes etc. 
  164.  *
  165.  * XXXben - Some of this stuff should go into a management-ey interface, 
  166.  *          some into an app-startup-ey interface.
  167.  */
  168. [scriptable, uuid(a3f5396c-a6e8-414a-8fbc-c8d831746328)]
  169. interface nsIExtensionManager : nsISupports
  170. {
  171.   /**
  172.    * Starts the Extension Manager, checking for item changes, additions and
  173.    * removals, and finishing pending operations.
  174.    * @param   commandLine
  175.    *          The command line the application was started with.
  176.    * @returns true if the application has rewritten the extensions.ini file
  177.    *          and needs to restart to register components/chrome etc, 
  178.    *          false otherwise
  179.    */
  180.   boolean start(in nsICommandLine commandLine);
  181.  
  182.   /** 
  183.    * Determines if there are incompatible items installed (and offers to
  184.    * upgrade them to newer versions if available, via a UI). 
  185.    * @returns true if there were incompatible items that were disabled
  186.    *          and the application needs to restart to re-register components,
  187.    *          chrome etc, false otherwise.
  188.    */
  189.   boolean checkForMismatches();
  190.  
  191.   /**
  192.    * Handle command line flags, e.g. -install-global-[extension|theme]
  193.    * @param   cmdLine
  194.    *          the command line the application was started with
  195.    * XXXben - move this off this API - currently it is only used for 
  196.    *          global installation, and the apprunner can do this directly
  197.    *          with |installItemFromFile|
  198.    */
  199.   void handleCommandLineArgs(in nsICommandLine cmdline);
  200.  
  201.   /**
  202.    * Gets the Install Location for an item
  203.    * @param   id
  204.    *          The GUID of the item
  205.    * @returns The Install Location where the item is installed.
  206.    */
  207.   nsIInstallLocation getInstallLocation(in AString id);
  208.  
  209.   /**
  210.    * An enumeration of all registered Install Items
  211.    */
  212.   readonly attribute nsISimpleEnumerator installLocations;
  213.  
  214.   /**
  215.    * Installs an item from a XPI/JAR file into the location specified. 
  216.    * @param   xpiFile
  217.    *          The source file to install from. This function stages a copy
  218.    *          of this file for persistence across potential application 
  219.    *          restarts, you are responsible for removing the file you pass
  220.    *          in. 
  221.    * @param   installLocationKey
  222.    *          The name identifier of an Install Location to install into.
  223.    */
  224.   void installItemFromFile(in nsIFile xpiFile, in AString installLocationKey);
  225.  
  226.   /**
  227.    * Uninstalls an item
  228.    * @param   id
  229.    *          The GUID of the item.
  230.    */
  231.   void uninstallItem(in AString id);
  232.  
  233.   /**
  234.    * Enables a disabled item
  235.    * @param   id
  236.    *          The GUID of the item.
  237.    */
  238.   void enableItem(in AString id);
  239.  
  240.   /**
  241.    * Disables an enabled item
  242.    * @param   id
  243.    *          The GUID of the item.
  244.    */
  245.   void disableItem(in AString id);
  246.  
  247.   /**
  248.    * Checks for updates to a list of items.
  249.    * @param   items
  250.    *          An array of nsIUpdateItems to check for updates for.
  251.    * @param   itemCount
  252.    *          The length of |items|
  253.    * @param   versionUpdateOnly
  254.    *          false if this check should find the newest versions available,
  255.    *          true if it should only find newer target application compatibility
  256.    *          information for the currently installed version.
  257.    *          2 if this check should only find target application compatibility
  258.    *          information for the currently installed version and synchronize
  259.    *          the values.
  260.    * @param   listener
  261.    *          An nsIAddonUpdateCheckListener object which will be notified during
  262.    *          the update check process. 
  263.    */
  264.    void update([array, size_is(itemCount)] in nsIUpdateItem items,
  265.                in unsigned long itemCount, 
  266.                in unsigned long versionUpdateOnly,
  267.                in nsIAddonUpdateCheckListener listener);
  268.  
  269.   /**
  270.    * Gets a nsIUpdateItem for the item with the specified id.
  271.    * @param   id
  272.    *          The GUID of the item to construct a nsIUpdateItem for.
  273.    * @returns The nsIUpdateItem representing the item.
  274.    */
  275.   nsIUpdateItem getItemForID(in AString id);
  276.  
  277.   /**
  278.    * Retrieves a list of visible nsIUpdateItems of items matching the 
  279.    * specified type.
  280.    * @param   type
  281.    *          The type of item to return.
  282.    * @param   countRef
  283.    *          The XPCJS reference to the number of items returned.
  284.    * @returns An array of nsIUpdateItems matching the id/type filter.
  285.    *
  286.    * XXXben - it would be good if this function took an optional 
  287.    *          install location.
  288.    */
  289.   void getItemList(in unsigned long type, out unsigned long itemCount,
  290.                    [retval, array, size_is(itemCount)] out nsIUpdateItem items);
  291.  
  292.   /**
  293.    * Retrieves a list of nsIUpdateItems of items that are incompatible
  294.    * with the supplied parameters.
  295.    * @param   id
  296.    *          The id of the application to check compatibility against
  297.    * @param   version
  298.    *          The version of the application to check compatibility against
  299.    * @param   type
  300.    *          The type of item to return
  301.    * @param   includeDisabled
  302.    *          true if disabled items should be included in the result set, 
  303.    *          false otherwise
  304.    * @param   countRef
  305.    *          The XPCJS reference to the number of items returned.
  306.    * @returns An array of incompatible nsIUpdateItems.
  307.    */
  308.   void getIncompatibleItemList(in AString id, 
  309.                                in AString version,
  310.                                in unsigned long type,
  311.                                in boolean includeDisabled,
  312.                                out unsigned long itemCount,
  313.                                [retval, array, size_is(itemCount)] out nsIUpdateItem items);
  314.  
  315.   /**
  316.    * The Extensions Datasource
  317.    * XXXben - the datasource should be registered with the RDF system, so it 
  318.    *          can be accessed via rdf:extensions, and not exposed through the API
  319.    *          like this.
  320.    */
  321.   readonly attribute nsIRDFDataSource datasource;
  322.  
  323.   /**
  324.    * Adds active download entries to the UI
  325.    * @param   items
  326.    *          A list of nsIUpdateItems to entries to add
  327.    * @param   itemCount
  328.    *          The length of |items|
  329.    * @param   fromChrome
  330.    *          true when called from chrome
  331.    *          false when not called from chrome (e.g. web page)
  332.    */
  333.   void addDownloads([array, size_is(itemCount)] in nsIUpdateItem items,
  334.                     in unsigned long itemCount, in boolean fromChrome);
  335.  
  336.   /**
  337.    * Removes an active download from the UI
  338.    * @param   url
  339.    *          The URL of the active download to remove
  340.    */
  341.   void removeDownload(in AString url);
  342.  
  343.   /**
  344.    * Adds a download progress listener so the front end can listen to download
  345.    * and install progress.
  346.    * @param   listener
  347.    *          The listener to add
  348.    * @returns the index of the added listen in the listener list. 
  349.    */
  350.   long addUpdateListener(in nsIAddonUpdateListener listener);
  351.  
  352.   /**
  353.    * Removes a download progress listener.
  354.    * @param   index
  355.    *          The index of the listener to remove.
  356.    */
  357.   void removeUpdateListenerAt(in long index);
  358.  
  359.   /**
  360.    * Move an Item to the index of another item in its container.
  361.    * @param   movingID
  362.    *          The ID of an item to be moved.
  363.    * @param   destinationID
  364.    *          The ID of an item to move an item to.
  365.    */
  366.   void moveToIndexOf(in AString movingID, in AString destinationID);
  367. };
  368.  
  369. /**
  370.  * An item managed by the Extension System. Contains metadata that describes 
  371.  * the item.
  372.  * XXXben work in progress, the name of this interface will change after the
  373.  *        update system is complete, probably to nsIAddon
  374.  */
  375. [scriptable, uuid(7f952767-427f-402b-8114-f80c95d1980d)]
  376. interface nsIUpdateItem : nsISupports
  377. {
  378.   /**
  379.    * The GUID of the item.
  380.    */
  381.   readonly attribute AString  id;
  382.  
  383.   /**
  384.    * The Version of the item, in FVF format.
  385.    */
  386.   readonly attribute AString  version;
  387.  
  388.   /**
  389.    * The minimum version of the application that this item works with, 
  390.    * in FVF format.
  391.    */
  392.   readonly attribute AString  minAppVersion;
  393.  
  394.   /**
  395.    * The maximum version of the application that this item works with,
  396.    * in FVF format.
  397.    */
  398.   readonly attribute AString  maxAppVersion;
  399.  
  400.   /**
  401.    * The name of the Install Location where this item is installed.
  402.    */
  403.   readonly attribute AString  installLocationKey;
  404.  
  405.   /**
  406.    * The name of this item.
  407.    */
  408.   readonly attribute AString  name;
  409.  
  410.   /**
  411.    * The URL of the XPI where this item can be downloaded.
  412.    */
  413.   readonly attribute AString  xpiURL;
  414.  
  415.   /**
  416.    * The string Hash for the XPI file. Can be null and if supplied must be in
  417.    * the format of "type:hash" (see the types in nsICryptoHash and
  418.    * nsIXPInstallManager::initManagerWithHashes).
  419.    */
  420.   readonly attribute AString  xpiHash;
  421.  
  422.   /**
  423.    * The URL of the icon that can be shown for this item.
  424.    */
  425.   readonly attribute AString  iconURL;
  426.  
  427.   /**
  428.    * The URL of the update RDF file for this item.
  429.    */
  430.   readonly attribute AString  updateRDF;
  431.   
  432.   const unsigned long TYPE_APP         = 0x01;
  433.   const unsigned long TYPE_EXTENSION   = 0x02;
  434.   const unsigned long TYPE_THEME       = 0x04;
  435.   const unsigned long TYPE_LOCALE      = 0x08;
  436.   const unsigned long TYPE_PLUGIN      = 0x10;
  437.   const unsigned long TYPE_MULTI_XPI   = 0x20;
  438.   const unsigned long TYPE_ADDON       = TYPE_EXTENSION + TYPE_THEME + TYPE_LOCALE + TYPE_PLUGIN;
  439.   const unsigned long TYPE_ANY         = TYPE_APP + TYPE_ADDON;
  440.  
  441.   /**
  442.    * The type of this item.
  443.    */
  444.   readonly attribute long type;
  445.  
  446.   /**
  447.    * Initializes this Item object.
  448.    */
  449.   void init(in AString id, in AString version, 
  450.             in AString installLocationKey, in AString minAppVersion, 
  451.             in AString maxAppVersion, in AString name,
  452.             in AString downloadURL, in AString xpiHash, in AString iconURL,
  453.             in AString updateURL, in long type);
  454.  
  455.   /**
  456.    * Returns a JS Object source representing an nsIUpdateItem.
  457.    */
  458.   readonly attribute AString objectSource;
  459. };
  460.  
  461. /**
  462.  * Interface for handling download and install progress notifications for 
  463.  * addons.
  464.  */
  465. [scriptable, uuid(bb86037c-98c1-4c22-8e03-1e4c9fc89a8e)]
  466. interface nsIAddonUpdateListener : nsISupports
  467. {
  468.   /**
  469.    * Install/Download state has changed
  470.    * @param   addon
  471.    *          The addon that state changed for
  472.    * @param   state
  473.    *          The new state. States are defined in nsIXPIProgressDialog
  474.    * @param   value
  475.    *          Some data about the new state
  476.    */
  477.   void onStateChange(in nsIUpdateItem addon, in short state, in long value);
  478.  
  479.   /**
  480.    * Progress occurred in the download/install operation
  481.    * @param   addon
  482.    *          The addon that progress occurred for
  483.    * @param   value
  484.    *          The value of the current progress
  485.    * @param   maxValue
  486.    *          The maximum value |value| can reach
  487.    */
  488.   void onProgress(in nsIUpdateItem addon, in unsigned long value, 
  489.                   in unsigned long maxValue);
  490. };
  491.  
  492. /**
  493.  * Interface for handling notifications during the addon update check process.
  494.  */
  495. [scriptable, uuid(c946119f-9e7c-41aa-a794-803148045350)]
  496. interface nsIAddonUpdateCheckListener : nsISupports
  497. {
  498.   /**
  499.    * Addon update has begun
  500.    */
  501.   void onUpdateStarted();
  502.  
  503.   const unsigned long STATUS_NONE = 0;
  504.   const unsigned long STATUS_UPDATE = 1;
  505.   const unsigned long STATUS_VERSIONINFO = 2;
  506.   const unsigned long STATUS_DATA_FOUND = 
  507.     STATUS_UPDATE + STATUS_VERSIONINFO;
  508.   const unsigned long STATUS_FAILURE = 4;
  509.   const unsigned long STATUS_NO_UPDATE = 8;
  510.   const unsigned long STATUS_DISABLED = 16;
  511.   const unsigned long STATUS_APP_MANAGED = 32;
  512.   const unsigned long STATUS_READ_ONLY = 64;
  513.   const unsigned long STATUS_PENDING_OP = 128;
  514.   const unsigned long STATUS_NOT_MANAGED = 256;
  515.   const unsigned long STATUS_DISALLOWED =
  516.     STATUS_DISABLED + STATUS_APP_MANAGED + STATUS_READ_ONLY +
  517.     STATUS_PENDING_OP + STATUS_NOT_MANAGED;
  518.  
  519.   /**
  520.    * Addon update has ended
  521.    */
  522.   void onUpdateEnded();
  523.  
  524.   /**
  525.    * Update for an individual addon has begun
  526.    * @param   addon
  527.    *          A nsIUpdateItem object representing the addon being updated
  528.    */
  529.   void onAddonUpdateStarted(in nsIUpdateItem addon);
  530.  
  531.   /**
  532.    * Update for an individual addon has ended
  533.    * @param   addon
  534.    *          A nsIUpdateItem object representing the addon being updated
  535.    * @param   status
  536.    *          The success or failure code of the update operation
  537.    */
  538.   void onAddonUpdateEnded(in nsIUpdateItem addon, in long status);
  539. };
  540.  
  541. %{ C++
  542. /**
  543.  * Install Location Key for Application-Global Items
  544.  */
  545. #define NS_INSTALL_LOCATION_APPGLOBAL NS_LITERAL_STRING("app-global")
  546.  
  547. /**
  548.  * Install Location Key for Application-Profile Items
  549.  */
  550. #define NS_INSTALL_LOCATION_APPPROFILE NS_LITERAL_STRING("app-profile")
  551.  
  552. /** 
  553.  * The category that contains a list of contract-ids to Install Location 
  554.  * services.
  555.  */
  556. #define CATEGORY_INSTALL_LOCATIONS "extension-install-locations"
  557.  
  558. /**
  559.  * The observer topic to listen to for actions performed on installed
  560.  * items.
  561.  */
  562. #define EM_ACTION_REQUESTED_TOPIC "em-action-requested"
  563.  
  564. #define EM_ITEM_INSTALLED   "item-installed"
  565. #define EM_ITEM_UPGRADED    "item-upgraded"
  566. #define EM_ITEM_UNINSTALLED "item-uninstalled"
  567. #define EM_ITEM_ENABLED     "item-enabled"
  568. #define EM_ITEM_DISABLED    "item-disabled"
  569. #define EM_ITEM_CANCEL      "item-cancel-action"
  570.  
  571. %}
  572.  
  573.